<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../style.css" type="text/css" media="screen">
<link rel="stylesheet" href="../../../../print.css" type="text/css" media="print">
<meta content="FrontController,com.adobe.cairngorm.control.FrontController,commands,addCommand,removeCommand,executeCommand,getCommand" name="keywords">
<title>com.adobe.cairngorm.control.FrontController</title>
</head>
<body>
<script type="text/javascript" language="javascript" src="../../../../asdoc.js"></script><script type="text/javascript" language="javascript" src="../../../../cookies.js"></script><script type="text/javascript" language="javascript">
<!--
				asdocTitle = 'FrontController - Adobe Consulting EMEA - Cairngorm';
				var baseRef = '../../../../';
				window.onload = configPage;
			--></script>
<table style="display:none" id="titleTable" cellspacing="0" cellpadding="0" class="titleTable">
<tr>
<td align="left" class="titleTableTitle">API Documentation</td><td align="right" class="titleTableTopNav"><a onclick="loadClassListFrame('../../../../all-classes.html')" href="../../../../package-summary.html">All&nbsp;Packages</a>&nbsp;|&nbsp;<a onclick="loadClassListFrame('../../../../all-classes.html')" href="../../../../class-summary.html">All&nbsp;Classes</a>&nbsp;|&nbsp;<a onclick="loadClassListFrame('../../../../index-list.html')" href="../../../../all-index-A.html">Index</a>&nbsp;|&nbsp;<a href="../../../../index.html?com/adobe/cairngorm/control/FrontController.html&amp;com/adobe/cairngorm/control/class-list.html" id="framesLink1">Frames</a><a onclick="parent.location=document.location" href="" style="display:none" id="noFramesLink1">No&nbsp;Frames</a></td><td rowspan="3" align="right" class="titleTableLogo"><img alt="Adobe Logo" title="Adobe Logo" class="logoImage" src="../../../../images/logo.jpg"></td>
</tr>
<tr class="titleTableRow2">
<td align="left" id="subTitle" class="titleTableSubTitle">Class&nbsp;FrontController</td><td align="right" id="subNav" class="titleTableSubNav"><a href="#propertySummary">Properties</a>&nbsp;| <a href="#methodSummary">Methods</a></td>
</tr>
<tr class="titleTableRow3">
<td colspan="2">&nbsp;</td>
</tr>
</table>
<script type="text/javascript" language="javascript">
<!--
if (!isEclipse() || window.name != ECLIPSE_FRAME_NAME) {titleBar_setSubTitle("Class FrontController"); titleBar_setSubNav(false,true,false,false,false,false,true,false,false,false,false,false,false,false);}
--></script>
<div class="MainContent">
<table cellspacing="0" cellpadding="0" class="classHeaderTable">
<tr>
<td class="classHeaderTableLabel">Package</td><td><a onclick="javascript:loadClassListFrame('class-list.html')" href="package-detail.html">com.adobe.cairngorm.control</a></td>
</tr>
<tr>
<td class="classHeaderTableLabel">Class</td><td class="classSignature">public class FrontController</td>
</tr>
</table>
<p></p>
    A base class for an application specific front controller,
    that is able to dispatch control following particular user gestures to appropriate
    command classes.
        <p>
    The Front Controller is the centralised request handling class in a
    Cairngorm application.  Throughout the application architecture are
    scattered a number of CairngormEventDispatcher.getInstance().dispatchEvent( event )
    method calls, that signal to the listening controller that a user gesture
    has occured.
    </p>
        <p>
    The role of the Front Controller is to first register all the different
    events that it is capable of handling against worker classes, called
    command classes.  On hearing an application event, the Front Controller
    will look up its table of registered events, find the appropriate
    command for handling of the event, before dispatching control to the
    command by calling its execute() method.
    </p>
        <p>
    Commands are added to the front controller with a weak reference,
    meaning that when the command is garbage collected, the reference in
    the controller is also garbage collected.
    </p>
    
    <p>
    The Front Controller is a base-class that  listen for events 
    dispatched by CairngormEventDispatcher.  In a 
    Cairngorm application, the developer should create a class that
    extends the FrontController, and in the constructor of their
    application specific controller, they should make numerous calls to
    addCommand() to register all the expected events with application
    specific command classes.
    </p>
        <p>
    Consider a LoginController, that is the main controller for a Login
    application that has 2 user gestures - Login and Logout.  The application
    will have 2 buttons, "Login" and "Logout" and in the click handler for
    each button, one of the following methods is executed:
    </p>
        <pre>
    public function doLogin() : void
    {
       var event : LoginEvent = new LoginEvent( username.text, password.text );
       CairngormEventDispatcher.getInstance.dispatchEvent( event );
    }
    
    public function doLogout() : void
    {
       var event : LogoutEvent = new LogoutEvent();
       CairngormEventDispatcher.getInstance.dispatchEvent( event );
    }
    </pre>
    
    <p>
    We would create LoginController as follows:
    </p>
        <pre>
    class LoginController extends com.adobe.cairngorm.control.FrontController
    {
       public function LoginController()
       {
          initialiseCommands();
       }
    
       public function initialiseCommands() : void
       {
          addCommand( LoginEvent.EVENT_LOGIN, LoginCommand );
          addCommand( LogoutEvent.EVENT_LOGOUT, LogoutCommand );
       }
      
    }
    </pre>
        <p>
    In our concrete implementation of a FrontController, LoginController, we
    register the 2 events that are expected for broadcast - login and logout -
    using the addCommand() method of the parent FrontController class, to
    assign a command class to each event.
    </p>
        <p>
    Adding a new use-case to a Cairngorm application is as simple as
    registering the event against a command in the application Front Controller,
    and then creating the concrete command class.
    </p>
    
    <p>
    The concrete implementation of the FrontController, LoginController,
    should be created once and once only (as we only want a single controller
    in our application architecture).  Typically, in our main application, we
    would declare our FrontController child class as a tag, which should be placed
    above any tags which have a dependency on the FrontController
    </p>
        <pre>
    &lt;mx:Application  xmlns:control="com.domain.project.control.LoginController"   ... &gt;
          &lt;control:LoginController id="controller" /&gt;
         ...
    
    </pre>
        <p></p>
<p>
<span class="classHeaderTableLabel">See also</span>
</p>
<div class="seeAlso">
<a href="../commands/ICommand.html" target="">com.adobe.cairngorm.commands.ICommand</a>
</div>
<br>
<hr>
</div>
<a name="propertySummary"></a><a name="protectedPropertySummary"></a>
<div class="summarySection">
<div class="summaryTableTitle">Protected Properties</div>
<table id="summaryTableProtectedProperty" class="summaryTable " cellpadding="3" cellspacing="0">
<tr>
<th>&nbsp;</th><th colspan="2">Property</th><th class="summaryTableOwnerCol">Defined&nbsp;by</th>
</tr>
<tr class="">
<td class="summaryTablePaddingCol">&nbsp;</td><td class="summaryTableInheritanceCol">&nbsp;</td><td class="summaryTableSignatureCol"><a class="signatureLink" href="#commands">commands</a> : Dictionary<div class="summaryTableDescription">
      Dictionary of event name to command class mappings
      </div>
</td><td class="summaryTableOwnerCol">FrontController</td>
</tr>
</table>
</div>
<a name="methodSummary"></a>
<div class="summarySection">
<div class="summaryTableTitle">Public Methods</div>
<table id="summaryTableMethod" class="summaryTable " cellpadding="3" cellspacing="0">
<tr>
<th>&nbsp;</th><th colspan="2">Method</th><th class="summaryTableOwnerCol">Defined&nbsp;by</th>
</tr>
<tr class="">
<td class="summaryTablePaddingCol">&nbsp;</td><td class="summaryTableInheritanceCol">&nbsp;</td><td class="summaryTableSignatureCol">
<div class="summarySignature">
<a class="signatureLink" href="#addCommand()">addCommand</a>(commandName:String, commandRef:Class, useWeakReference:Boolean = true):void</div>
<div class="summaryTableDescription">
      Registers a ICommand class with the Front Controller, against an event name
      and listens for events with that name.</div>
</td><td class="summaryTableOwnerCol">FrontController</td>
</tr>
<tr class="">
<td class="summaryTablePaddingCol">&nbsp;</td><td class="summaryTableInheritanceCol">&nbsp;</td><td class="summaryTableSignatureCol">
<div class="summarySignature">
<a class="signatureLink" href="#removeCommand()">removeCommand</a>(commandName:String):void</div>
<div class="summaryTableDescription">
      Deregisters an ICommand class with the given event name from the Front Controller 
            </div>
</td><td class="summaryTableOwnerCol">FrontController</td>
</tr>
</table>
</div>
<a name="protectedMethodSummary"></a>
<div class="summarySection">
<div class="summaryTableTitle">Protected Methods</div>
<table id="summaryTableProtectedMethod" class="summaryTable " cellpadding="3" cellspacing="0">
<tr>
<th>&nbsp;</th><th colspan="2">Method</th><th class="summaryTableOwnerCol">Defined&nbsp;by</th>
</tr>
<tr class="">
<td class="summaryTablePaddingCol">&nbsp;</td><td class="summaryTableInheritanceCol">&nbsp;</td><td class="summaryTableSignatureCol">
<div class="summarySignature">
<a class="signatureLink" href="#executeCommand()">executeCommand</a>(event:<a href="CairngormEvent.html">CairngormEvent</a>):void</div>
<div class="summaryTableDescription">
      Executes the command
      </div>
</td><td class="summaryTableOwnerCol">FrontController</td>
</tr>
<tr class="">
<td class="summaryTablePaddingCol">&nbsp;</td><td class="summaryTableInheritanceCol">&nbsp;</td><td class="summaryTableSignatureCol">
<div class="summarySignature">
<a class="signatureLink" href="#getCommand()">getCommand</a>(commandName:String):Class</div>
<div class="summaryTableDescription">
      Returns the command class registered with the command name.</div>
</td><td class="summaryTableOwnerCol">FrontController</td>
</tr>
</table>
</div>
<script type="text/javascript" language="javascript">
<!--
showHideInherited();
--></script>
<div class="MainContent">
<a name="propertyDetail"></a>
<div class="detailSectionHeader">Property detail</div>
<a name="commands"></a>
<table cellspacing="0" cellpadding="0" class="detailHeader">
<tr>
<td class="detailHeaderName">commands</td><td class="detailHeaderType">property</td>
</tr>
</table>
<div class="detailBody">
<code>protected var commands:Dictionary</code><p>
      Dictionary of event name to command class mappings
      </p></div>
<a name="methodDetail"></a>
<div class="detailSectionHeader">Method detail</div>
<a name="addCommand()"></a>
<table cellspacing="0" cellpadding="0" class="detailHeader">
<tr>
<td class="detailHeaderName">addCommand</td><td class="detailHeaderParens">()</td><td class="detailHeaderType">method</td>
</tr>
</table>
<div class="detailBody">
<code>public function addCommand(commandName:String, commandRef:Class, useWeakReference:Boolean = true):void</code><p>
      Registers a ICommand class with the Front Controller, against an event name
      and listens for events with that name.
            </p><p>When an event is broadcast that matches commandName,
      the ICommand class referred to by commandRef receives control of the
      application, by having its execute() method invoked.</p>
            <span class="label">Parameters</span>
<table border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="20px"></td><td><code><span class="label">commandName</span>:String</code> &mdash; The name of the event that will be broadcast by the
      when a particular user gesture occurs, eg "login"
            </td>
</tr>
<tr>
<td class="paramSpacer">&nbsp;</td>
</tr>
<tr>
<td width="20px"></td><td><code><span class="label">commandRef</span>:Class</code> &mdash; An ICommand Class reference upon which execute()
      can be called when the Front Controller hears an event broadcast with
      commandName. Typically, this argument is passed as "LoginCommand" 
      or similar.
      
      </td>
</tr>
<tr>
<td class="paramSpacer">&nbsp;</td>
</tr>
<tr>
<td width="20px"></td><td><code><span class="label">useWeakReference</span>:Boolean</code> (default = <code>true</code>)<code></code> &mdash; A Boolean indicating whether the controller
      should added as a weak reference to the CairngormEventDispatcher,
      meaning it will eligibile for garbage collection if it is unloaded from 
      the main application.
      </td>
</tr>
</table>
</div>
<a name="executeCommand()"></a>
<table cellspacing="0" cellpadding="0" class="detailHeader">
<tr>
<td class="detailHeaderName">executeCommand</td><td class="detailHeaderParens">()</td><td class="detailHeaderType">method</td><td class="detailHeaderRule">&nbsp;</td>
</tr>
</table>
<div class="detailBody">
<code>protected function executeCommand(event:<a href="CairngormEvent.html">CairngormEvent</a>):void</code><p>
      Executes the command
      </p><span class="label">Parameters</span>
<table border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="20px"></td><td><code><span class="label">event</span>:<a href="CairngormEvent.html">CairngormEvent</a></code></td>
</tr>
</table>
</div>
<a name="getCommand()"></a>
<table cellspacing="0" cellpadding="0" class="detailHeader">
<tr>
<td class="detailHeaderName">getCommand</td><td class="detailHeaderParens">()</td><td class="detailHeaderType">method</td><td class="detailHeaderRule">&nbsp;</td>
</tr>
</table>
<div class="detailBody">
<code>protected function getCommand(commandName:String):Class</code><p>
      Returns the command class registered with the command name. 
      </p><span class="label">Parameters</span>
<table border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="20px"></td><td><code><span class="label">commandName</span>:String</code></td>
</tr>
</table>
<p></p>
<span class="label">Returns</span>
<table border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="20"></td><td><code>Class</code></td>
</tr>
</table>
</div>
<a name="removeCommand()"></a>
<table cellspacing="0" cellpadding="0" class="detailHeader">
<tr>
<td class="detailHeaderName">removeCommand</td><td class="detailHeaderParens">()</td><td class="detailHeaderType">method</td><td class="detailHeaderRule">&nbsp;</td>
</tr>
</table>
<div class="detailBody">
<code>public function removeCommand(commandName:String):void</code><p>
      Deregisters an ICommand class with the given event name from the Front Controller 
            </p><span class="label">Parameters</span>
<table border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="20px"></td><td><code><span class="label">commandName</span>:String</code> &mdash; The name of the event that will be broadcast by the
      when a particular user gesture occurs, eg "login"
            </td>
</tr>
</table>
</div>
<br>
<br>
<hr>
<br>
<p></p>
<center class="copyright"> 
</center>
</div>
</body>
</html>
<!-- -->
